Bug 261064

Summary: /docs/ minor update; orientation; put the new documentation site, and its content, in context
Product: Documentation Reporter: Graham Perrin <grahamperrin>
Component: WebsiteAssignee: Sergio Carlavilla Delgado <carlavilla>
Status: Closed FIXED    
Severity: Affects Only Me CC: carlavilla, doc
Priority: ---    
Version: Latest   
Hardware: Any   
OS: Any   
URL: https://www.freebsd.org/docs/

Description Graham Perrin freebsd_committer freebsd_triage 2022-01-09 16:05:16 UTC 
At <https://www.freebsd.org/docs/> the most prominent link to 'documentation' (in the sole single-sentence paragraph) refers to traditional: 

<https://www.freebsd.org/docs/books/>

– ignoring (for a moment) the 'books' part of the URL, this is fine; there's a variety of documentation from multiple domains. 

We do have the two references to <https://docs.freebsd.org/en/>: 

* 'Documentation' in the navigation bar

* 'Documentation' at the head of the sidebar

– however the page itself <https://www.freebsd.org/docs/> does not make clear that the word documentation currently has two very different meanings (different destinations). 


Maybe re-word the existing paragraph. Something like: 


> Our main <documentation site> comprises material that's managed by 
> the FreeBSD Documentation Project. Contributions from the 
> community are encouraged. 
> 
> Sidebar links, to the left, include: 
> 
> * the FreeBSD Handbook and other popular Documentation Project items
> 
> * items from other areas, including the FreeBSD Foundation.


NB: 

* no use of the word 'portal'

* no more than one link in the body text.


Then add a sidebar link 'Overview' (beneath 'Documentation') with reference to <https://www.freebsd.org/docs/books/>.
Comment 1 Sergio Carlavilla Delgado freebsd_committer freebsd_triage 2022-01-30 13:45:24 UTC 
Maybe we should create a redirect here and make an automatic link to docs.freebsd.org instead of having a paragraph here.

There's also a duplicated list of books and articles in https://www.freebsd.org/docs/books/

I don't know if this still makes sense.

I'm gonna send an email to Doceng to discuss this.

Thanks for pointing this out :)