User avatar
aallan
Raspberry Pi Trading Employee & Forum Moderator
Raspberry Pi Trading Employee & Forum Moderator
Posts: 227
Joined: Mon Feb 09, 2015 11:30 am
Location: Exeter, UK
Contact: Website Twitter

Documentation Update

Mon Jun 07, 2021 11:47 am

We're in the process of transitioning the documentation from the current Markdown-based source format to Asciidoc. This will help automate creating a new and improved documentation site that will fit with the newer website styling and have much-improved navigation.

In the process, we will also be addressing structural issues and reducing the overall amount of non-core documentation to reduce the overall load in maintaining the documentation site.

See https://github.com/raspberrypi/document ... ssues/1911 for further details.
Head of Documentation
Raspberry Pi (Trading) Limited
About me, http://alasdairallan.com

User avatar
aallan
Raspberry Pi Trading Employee & Forum Moderator
Raspberry Pi Trading Employee & Forum Moderator
Posts: 227
Joined: Mon Feb 09, 2015 11:30 am
Location: Exeter, UK
Contact: Website Twitter

Re: Documentation Update

Mon Jun 07, 2021 8:32 pm

aallan wrote:
Mon Jun 07, 2021 11:47 am
See https://github.com/raspberrypi/document ... ssues/1911 for further details.

…discussion around these changes on Github Issue please.
Head of Documentation
Raspberry Pi (Trading) Limited
About me, http://alasdairallan.com

User avatar
aallan
Raspberry Pi Trading Employee & Forum Moderator
Raspberry Pi Trading Employee & Forum Moderator
Posts: 227
Joined: Mon Feb 09, 2015 11:30 am
Location: Exeter, UK
Contact: Website Twitter

Re: Documentation Update

Mon Aug 09, 2021 11:12 am

aallan wrote:
Mon Jun 07, 2021 8:32 pm
We're in the process of transitioning the documentation from the current Markdown-based source format to Asciidoc. This will help automate creating a new and improved documentation site that will fit with the newer website styling and have much-improved navigation…

The new documentation site is now live.

The site is built and deployed directly from the documentation repository using Github Actions when someone pushes to the master branch. However, we’ll be working on the develop branch in the repository, which is now the default branch you’ll now get when you take a fresh checkout, and also the branch you should target for your pull requests.

We’ve always taken pull requests against the Markdown-based source behind our documentation site. Over the years as the documentation set has grown there have been hundreds of community contributors, who have made over 1,200 individual pull requests, ranging from fixing small typos, to contributing whole new sections.

With the introduction of the new site, we’re going to continue to take pull requests against the new Asciidoc-based documentation. However, we’re going to be a bit more targeted around what we’ll to accept into the documentation, and will be looking to keep the repository focussed on Raspberry Pi-specific things, rather than having generic Linux tutorial content.

The documentation itself will remain under a Creative Commons Attribution-Sharealike (CC BY-SA 4.0) license.

If you’re already a contributor, the easiest thing to do is to take a fresh checkout of the repository, because things have changed a lot today!
Head of Documentation
Raspberry Pi (Trading) Limited
About me, http://alasdairallan.com

User avatar
seamus
Posts: 39
Joined: Fri Sep 30, 2016 1:25 am

Re: Documentation Update

Tue Aug 10, 2021 3:07 am

I wonder if you'd be willing to share any thoughts or plans regarding what is to be done about all the broken links that these changes have created.

aBUGSworstnightmare
Posts: 4227
Joined: Tue Jun 30, 2015 1:35 pm

Re: Documentation Update

Tue Aug 10, 2021 5:16 am

Has someone considered usability of this, i.e. tested this on a tablet? Do you really expect us to scroll through pages without a propper table of contents?
Readability is realy downgrade by this 'improvement' (speaking of an access via tablet, not checked from PC yet).

User avatar
Imperf3kt
Posts: 4665
Joined: Tue Jun 20, 2017 12:16 am
Location: Australia
Contact: Twitter

Re: Documentation Update

Tue Aug 10, 2021 5:32 am

Has this been tested thoroughly? I really feel it hasn't.

As viewed from chrome 91 on an Android 9 device
Image
Last edited by Imperf3kt on Tue Aug 10, 2021 5:48 am, edited 2 times in total.
55:55:44:44:4C
52:4C:52:42:41

Rose tinted glasses are difficult to see through.

fruitoftheloom
Posts: 27226
Joined: Tue Mar 25, 2014 12:40 pm

Re: Documentation Update

Tue Aug 10, 2021 5:40 am

Imperf3kt wrote:
Tue Aug 10, 2021 5:32 am
Has this been tested thoroughly? I really feel it hasn't.

As viewed from chromium on an Android 9 device

+100% the web designers have left Mobile Device Users with a very bad experience, hardly worth perusing https://www.raspberrypi.org these days.

*slightly* better in Landscape.......
Take what I advise as advice not the utopian holy grail, and it is gratis !!

User avatar
aallan
Raspberry Pi Trading Employee & Forum Moderator
Raspberry Pi Trading Employee & Forum Moderator
Posts: 227
Joined: Mon Feb 09, 2015 11:30 am
Location: Exeter, UK
Contact: Website Twitter

Re: Documentation Update

Tue Aug 10, 2021 8:07 am

seamus wrote:
Tue Aug 10, 2021 3:07 am
I wonder if you'd be willing to share any thoughts or plans regarding what is to be done about all the broken links that these changes have created.

Links to individual `*.md` pages will not be redirected. We can't be expected to maintain, forever, a complex tree of links, and then redirect every page when the documentation is restructured, and then again when we restructure it the next time. I'm also about to embark on a large scale cull of the older, less relevant documentation. My current estimate is about 1/3 of the existing documentation will probably be deleted.

Going forward we'll probably set up some catch all redirects to top level category pages, but link rot is a thing everybody has to deal with.

Update: There now some category-level redirects in place, see raspberrypi/documentation#2010 for more details.
Head of Documentation
Raspberry Pi (Trading) Limited
About me, http://alasdairallan.com

fruitoftheloom
Posts: 27226
Joined: Tue Mar 25, 2014 12:40 pm

Re: Documentation Update

Tue Aug 10, 2021 9:40 am

aallan wrote:
Tue Aug 10, 2021 8:07 am
seamus wrote:
Tue Aug 10, 2021 3:07 am
I wonder if you'd be willing to share any thoughts or plans regarding what is to be done about all the broken links that these changes have created.

Links to individual `*.md` pages will not be redirected. We can't be expected to maintain, forever, a complex tree of links, and then redirect every page when the documentation is restructured, and then again when we restructure it the next time. I'm also about to embark on a large scale cull of the older, less relevant documentation. My current estimate is about 1/3 of the existing documentation will probably be deleted.

Going forward we'll probably set up some catch all redirects to top level category pages, but link rot is a thing everybody has to deal with.

Update: There now some category-level redirects in place, see raspberrypi/documentation#2010 for more details.

What about usability on SmartPhones with 4" / 5" Screens ?
Take what I advise as advice not the utopian holy grail, and it is gratis !!

User avatar
forLilith
Posts: 1
Joined: Thu Mar 18, 2021 1:47 pm

Re: Documentation Update

Wed Aug 18, 2021 2:50 pm

so, does it work with those phones?

GenkiFeral
Posts: 5
Joined: Fri Sep 10, 2021 3:06 pm

Re: Documentation Update

Fri Sep 10, 2021 3:32 pm

Less info to sift through would be helpful.
I've found a few rare sites that use a markdown-style side panel with an outline on the left of the screen to navigate. I love that idea and that is 50% of the reason why I've changed 95% of my documents to markdown.
That may not work in a forum or blog, of course. Just an idea.

Also, I bought the 8GB Pi 4 and am pulling my hair out trying to find better, updated info for it and the OSs that work with it (Debian server, in my case). The 64bit issue is so new that I think a section for for the 8Gb/64bit should be made. Seems that I can set up Raspberry Pi Lite OS headless, but not Debian (unable to SSH without a password). I'd guess users trying other OSs are having similar issues, if not exactly that one.
Because the info is so hard to get for the 8GB/64bit and the info is so new, I regret buying the 8GB model now. Sounds like the 4GB model may've been plenty for a server running a few containers (no graphics).
I am complaining about information, how it is dated, and organized and even edited. The process I am going through setting this pi up seems very inefficient.

drgeoff
Posts: 12562
Joined: Wed Jan 25, 2012 6:39 pm

Re: Documentation Update

Fri Sep 10, 2021 8:45 pm

GenkiFeral wrote:
Fri Sep 10, 2021 3:32 pm
... I regret buying the 8GB model now. Sounds like the 4GB model may've been plenty for a server running a few containers (no graphics).
Anything that works OK on the 4 Gbyte RPI4B will also work, without modification, at least as well, if not better, on the 8 Gbyte version.
Quis custodiet ipsos custodes?

wonderworldspace
Posts: 1
Joined: Sat Oct 30, 2021 5:33 pm

Re: Documentation Update

Sat Oct 30, 2021 5:39 pm

that will fit with the newer website styling and have much-improved navigation…

Joseph23
Posts: 2
Joined: Sat Jan 08, 2022 7:15 am

Re: Documentation Update

Mon Jan 17, 2022 10:52 am

Thanks bro to giving this type of knowledge Your passion about his own field knowledge always motivates me.

Return to “General discussion”