[Documentation] software proposal for Armbian wiki

[tkaiser]

This sounds to me like a standard FAQ section ?

 

Sure, since why should people take notice? A FAQ is a wall of text no one wants to read. We have download pages for every board we support each containing also a wall of text no one reads.

 

As usual it's a matter of perspective if one considers a single sentence regarding boot problems as first sentence even on top of the board picture pointing to the specific FAQ entry useful / necessary or not. Imagine a few words in big letters between the menu bar and the board picture: http://www.armbian.com/orange-pi-pc-plus/  pointing to a specific FAQ entry (https://github.com/igorpecovnik/lib/wiki/Getting-started#how-to-prepare-sd-card  is already too specific)

 

Does it really hurt adding something like 'Important to know: The kind of SD card you choose matters. Boot problems are most probably related to broken SD cards, burning process or insufficient power supply. Check this first' pointing to this FAQ entry?

 

Same here. Who will click on the 'documentation' link? Simply no one (this should be a pinned post in every sub forum that's always on top)

 

 

We are too involved and therefore too blind to get the idea that this would help newbies avoiding or solving the usual hardware related problems they run into since 'testing out Armbian' means: 'Ah look, there's a shitty 4 GB SD card lying around, let's burn Armbian on it! WTF? Doesn't even boot, better stay with the Lubuntu that overheats my board so badly since this Armbian crap doesn't work at all'. Same applies to the 'performance feeling' with such a crap card. It's horrible and that's what people attribute to Armbian and not to the shitty spare SD card they're currently using since on the good SD card is still the OS image they already run. We can try to hide these important informations somewhere in a FAQ or we can try to ensure that essential information gets to our users. And that means looking at the whole stuff with another one's eyes.

 

BTW: If you ask if the Wiki contents already replaced http://www.armbian.com/documentation/ then it seems you missed the WHOLE discussion. Congrats.

[Tido]

First to your last line:
A "link" dear Thomas,  is a connection, a bridge, a guiding light through your darkest night
- it doesn't make sense to maintain text on two places and no - I didn't study how Igor this combined - I simply asked.
 
I read it, every time - because it will save me time if some changes have been done that influence my way of working.
 
I do agree with you, that we need more structure in the documentation.

 Performance tweaks

    /tmp & /log = RAM, ramlog app saves logs to disk daily and on shut-down (Wheezy and Jessie w/o systemd)
    automatic IO scheduler. (check /etc/init.d/armhwinfo)
    journal data writeback enabled. (/etc/fstab)
    commit=600 to flush data to the disk every 10 minutes (/etc/fstab)
    optimized CPU frequency scaling 480-1010Mhz (392-996Mhz @Freescale, 600-2000Mhz @Exynos & S905) with interactive governor (/etc/init.d/cpufrequtils)
    eth0 interrupts are using dedicated core (Allwinner based boards)

To me they are not in a logical order i.e. my order (First Memory, than CPU):

• /tmp & /log = RAM, ramlog app saves logs to disk daily and on shut-down (Wheezy and Jessie w/o systemd)
• journal data writeback enabled. (/etc/fstab)
• commit=600 to flush data to the disk every 10 minutes (/etc/fstab)
• automatic IO scheduler. (check /etc/init.d/armhwinfo)
• optimized CPU frequency scaling 480-1010Mhz (392-996Mhz @Freescale, 600-2000Mhz @Exynos & S905) with interactive governor (/etc/init.d/cpufrequtils)
• eth0 interrupts are using dedicated core (Allwinner based boards)

Another idea coming from your inspiration above, if you hit the download link, it will take you down to the respective section i.e. Vanilla Kernel and the real download button is at the end of its section

One more

In the FAQ:
dd bs=1M if=filename.raw of=/dev/sdx

I would add at the end: && sync  
dd bs=1M if=filename.raw of=/dev/sdx && sync

So after command 1 (dd finished and only then), it will run a sync and flush all the RAM to the disc's.

Edit: Change some Text to bold, so that TK also recognizes it (more structure, logical order)

Edited June 27, 2016 by Tido

[tkaiser]

So you're talking about the order of horribly outdated information instead of the information itself (I thought we're talking about improving documentation? That means that every of these sentences has to be either deleted or reworked since this is outdated stuff back from the day Igor supported 5 boards and now we're dealing with +40)

 

Then what do you suggest? Anyone should change something that comes to your mind right now? Don't we have a wiki now? Shouldn't we talk about the processes how to alter the wiki's contents (who is allowed to do what? How can we integrate people not allowed to edit directly to contribute?) instead of polluting this thread with random nonsense like "someone should add '&& sync' somewhere"?

 

I stop here.

[Tido]

Edit my previous posting: Change some Text to bold, so that TK also recognizes it (more structure, logical order)

 -> as I said to you in the past, think about what I want express and not what you are thinking.

 

in Post no. 30 I wrote:

By the way, in the manual should be a small section "how to commit suggestion" or "help to improve this manual" and a couple words and links.

 

I guess this fits to your second paragraph. So where you are, I was already 3 posts ago

And as I am not the owner of this GitHub, nor has a dedicated GitHub been created - this belongs to the owner of the GitHub to discuss.

 

 

I already know that you wont stop  

[miked]

There are a few tasks mentioned in this thread:
- Documentation html software and layout (mkdocs output, toc, search etc.)
- Edit Armbian.com to integrate the new docs location. Also link to documentation pdf somewhere.
- Auto generate and process the docs/pdf on github documentation commits (now do this on wiki edits?)
- Tweak pdf generation to look like a professional book.
- Reordering/structuring documentation so both newbs and experts can easily get to what they need (is this a separate task?)
- General documentation rewriting and additions (these are separate tasks)
 
As far as I know, all of these tasks are being worked on.
I'm not currently working on any of them, let me know if I can help!

 

BTW: If you ask if the Wiki contents already replaced http://www.armbian.com/documentation/ then it seems you missed the WHOLE discussion. Congrats.

 

I got confused about this too. But it looks like GitHub wiki will be used as the documentation source (markdown), it will still be processed into pretty html and pdf for armbian.com?

[Igor]

I got confused about this too. But it looks like GitHub wiki will be used as the documentation source (markdown), it will still be processed into pretty html and pdf for armbian.com?

 

Currently I can't. Github plugin needs changes since it can't display wiki's files. Until this is solved, Github wiki will be used - as a redirection, to preserver proper links and lib/documentation will be trashed asap.

[tkaiser]

No idea, ask Igor instead.

 

I thought choosing a wiki should enable more people to contribute (since I thought naively that's what the difference makes between sending pull requests for text documents in a repo and a real wiki?). The most interesting question is IMO: How do we get there? How do we ease improving documentation and get others on board (since currently AFAIK only Igor, zador and me are able to edit the Wiki directly? If that's the case and should remain so then 3 people use a wiki as wiki, for everone else nothing changed or it got even worse -- see below).

 

Few days ago  we had 6 .md documents, now we have a few more:

lib.wiki:
	_Footer.md
	_Sidebar.md
	Advanced-features.md
	Allwinner-hardware-conf.md
	Build-options.md
	Build-preparation.md
	Build-process.md
	Changelog.md
	Contribute.md
	Fel-boot.md
	Fine-tuning.md
	Getting-started.md
	H3.md
	Home.md
	User-configurations.md

And TOC structure is contained in _Sidebar.md and not in the filesystem. I really don't see how that enables more people to contribute since access for people that can not directly edit the wiki got harder IMO. But maybe I just miss something?

 

And I also don't know what happens next. @lanefu explained a few times that he wants to jump in and check mkdocs and htmldoc and how to integrate that into normal Armbian pages (I've been fine with all proposals). So it would be the best to not change the internal structure of the wiki repo now again and again since obviously some scripting is needed to walk through

• check stuff out
• parse _Sidebar.md to get logical structure of documents
• create HTML using mkdocs and integrate it somehow into normal pages
• create PDF using htmldoc

On the other hand there's now a lot to do, we have broken links from the normal pages (H3 download pages) to orphaned .md documents in normal repo and some of the adjustments in the wiki make no sense at all (eg. splitting up the H3 FAQ and re-using the 5.06-5.15 version history for the normal logbook).

 

Again: My main concern is (was in the meantime) how we can improve documentation. And that means getting others to contribute in a reasonable and easy way. Did we achieve something like that already? Did anything improve (given that these questions come up NOW: Who's working on what? What's the goal? In which direction are we walking? And so on...)

[Igor]

Huh. I guess we need to slow down and clear out things first. 

 

Changes that I made to the documentation in past two days are not that big, not a step back (except making a mess / stress) and also not final. I did what I thought is the best and of course things can and should be changed.

 

Links on download page will be fixed to blog links (asap), like mentioned in previous post. Only direct links to documentation @github are currently broken.

 

Updating by others. I assumed wiki can be managed by non admin on some way but if this is not possible, we didn't do anything. I agree. So you are suggesting to move docs back to github, under documentations, that can be altered by anyone?

[zador.blood.stained]

Updating by others. I assumed wiki can be managed by non admin on some way but if this is not possible, we didn't do anything. I agree. So you are suggesting to move docs back to github, under documentations, that can be altered by anyone?

Editing can be enabled either for everyone or for collaborators only, so it's not that useful for receiving contributions from another users. But IMO GitHub wiki is still a good place to keep build script documentation.

[tkaiser]

Huh. I guess we need to slow down and clear out things first.

 

At least that was my intention. Maybe I look at the whole task from a different perspective since I tried out a few minutes to grab .md from github to pipe it through both mkdocs and htmldoc and see that structure is also an issue.

 

My research regarding github wiki permissions is like zador's: everyone or collaborators. So at this stage IMO we should evaluate adding a separate (empty) armbian-docs repo with wiki enabled for collaborators where we move all doc stuff too. And can add here everyone as collaborator who wants to join in (regarding lib repo I think it's better to have PRs as some sort of a barrier since hasty commits might break everything and waste huge amounts of time/efforts). Since a wiki without being able to use it as wiki is pretty worthless (and going back to lib/documentation isn't an option either)

 

Then @lanefu (or someone else -- I really think we should use this as a chance to involve all the users asking how to contribute) can evaluate how to check out the docs there, parsing _Sidebar.md properly to create mkdocs structure that will also be used by htmldoc. I did some further investigations yesterday and it seems just by using an approriate theme in mkdocs the HTML to be fed into htmldoc is already pretty perfect (just some tweaks needed eg. for youtube links).

 

My other concern is that you as one of the 'big guys' predetermining structure/contents in the wiki within a few hours might discourage others to contribute. Since they fear messing things up. But documentation is something where this doesn't really hurt. We need more of our users contributing and most probably also messing things up from time to time (practice makes perfect -- and reverting edits isn't an issue at all).

[Tido]

Editing can be enabled either for everyone or for collaborators only,

Editing only the Wiki, I suppose ?

if changes can be reversed, like with any other Wiki, then the risk is not that big to open it to everyone ?

Well at least like on sunxi or others you need a login on GitHub to edit the Wiki, right?

[zador.blood.stained]

Editing only the Wiki, I suppose ?

if changes can be reversed, like with any other Wiki, then the risk is not that big to open it to everyone ?

Well at least like on sunxi or others you need a login on GitHub to edit the Wiki, right?

1. Yes, Wiki only

2. Yes, each change can be reverted

3. Yes, you need a GitHub login

[tkaiser]

2. Yes, each change can be reverted

 

At least I give up now. We were talking about the following just a few days before:

• Creating one good PDF manual from our documentation (that's currently a few .md docs lying around somewhere)
• Then generating intermediate HTML from our docs to be included into armbian.com (as far as I understand currently there's Wordpress running and a github plugin used to transform MD to HTML?)

Then a few people looked into the technical details, discovered that the problem might be solvable but different header structure in different documents becomes a problem (there are more, eg the pipe symbol will be misinterpreted as a table separator and so on). That means: Adjusting all the docs to use the same structure is a requirement and also: the less documents the better. That means also understandig these technical postprocessing details is a requirement to contribute to documentation.

 

Then we discovered that it's possible to use github wiki as a simple editing engine since this mechanism can also be used to produce the MD documents we need for creating our documentation -- both HTML and PDF (mkdocs and htmldoc seemed to be accepted but I've no idea what happened in the meantime). That also means: github wiki is just a frontend to edit MD and not the presentation engine of the documentation.

 

But in the meantime everything has changed, the whole structure of our documentation has been splitted up obviously just to get a nicer display inside the wiki so the wiki itself became also the presentation engine. And now we're talking already about 'hey, just another wiki, let everyone edit this stuff, doesn't matter, we can revert this everytime'.

 

Allowing everyone to edit will break postprocessing for sure. IMO it's a requirement to have a consensus what's this wiki for (and this has changed within 24 hours -- from editing frontend to presentation engine) and to understand the technical requirements of the postprocessing (that have not even been defined since some people just tried stuff out but that has been obviously only a waste of time)

 

Final words:

• The old HTML representation of our user docs below http://www.armbian.com/documentation/(now just a redirect to the wiki) was pretty much worthless since anchors weren't supported and no clickable TOC generated. So you were only able to tell users to 'take an hour and read from here on' but not jump directly to specific sections (that's the reason why I linked to the MD docs on github most of the times since there anchors worked, eg. this -- these links here in the forums are all broken now since names of docs changed and the contents of lib/documentation will vanish anyway)
• Pretty much the same critics apply to markdown-pdf's output (lack of clickable structure, a PDF without navigation features is for people that print out the internet)
• IMO being able to link to specific documentation sections is essential if we really want that our users are able to benefit from documentation. Just saying 'Huh?! Here is a wall of text, read through in case you've a problem' isn't enough. IMO we need links from every subforum to the specific documentation section, same applies to every download page if/when board specific information are available (or for stuff like 'boot problems')

If we now start to think about improving documentation then why not first consider concerns like this and then start changing structure (which is generally bad since this will create broken links eg. from forum to docs)? An alternative to that would be a general purpose wiki like linux-sunxi but then using the github engine is plain wrong since it does not even support search.

[Igor]

My other concern is that you as one of the 'big guys' predetermining structure/contents in the wiki within a few hours might discourage others to contribute. 

 

Yes, you are perfectly right about this. Nothing to add.

 

Well, beside that I added a sidebar document and rearrange few sections, we still have more or less the same thing. If we have an (open) wiki anyone can edit and we want that even we would need to fix things sometimes. Wiki is still just a little better than what we had until now. It's an lite presentation engine. Docs created with some serious tools (mkimage) looks much better / pro style and they can be created out of the wiki the exact same way. But this job is, like we are discovering, not strait / trivial so it will take some time.

 

Some decisions should be made, since things are floating in the middle, links were changed and might change more. Blog rendering does not work with Wiki, but normal github, links to H3 info @download page is still broken (will be fixed during a day), we have lib/documents and wiki containing the same stuff with some minor changes. 

 

One can be wrong if we (currently, until things are solved better way) refer people to www.armbian.com/documentation ... This can be redirected anywhere.

[tkaiser]

we still have more or less the same thing

 

Nope, but as already said I give up. We were talking about improving documentation and that includes 'accessibility' and way more links to specific documentation sections. We already know that people constantly ask questions like 'is it possible to install Armbian to eMMC?' and instead of asking us why such questions pop up (obviously our documentation sucks even if we wrote the necessary steps somewhere) we simply ignore this.

 

The former HTML representation of various docs on armbian.com was pretty much useless (since 'TL;DR', no anchors/links to sections, no search through the whole documentation possible) and I thought we started a few days ago thinking together how to improve this? One way could be transforming our MD files using mkdocs to a nice HTML representation that can be integrated into armbian.com (main problem: How to maintain structure inside and accross different documents?) and a nice PDF manual (that is searchable and has a clickable TOC) can also solve most accessibility problems. Since 'RTFM' then means pointing people to the PDF link and let them search through a whole document and check the few hits for 'eMMC' to reference the example above)

 

Maybe you should think about this postprocessing first, also how to be able to create persistent links to documentation sections to see that the current wiki approach is not an improvement at all. EITHER a searchable wiki with unstructured contents that change on a daily basis you can link to (then we can answer any forum question with 'go search the wiki') OR a defined documentation process relying on MD docs that will be postprocessed and creates structured HTML one can link to in a consistent way and a fully blown PDF manual. 

 

Maybe it's necessary to play with mkdocs/htmldocs and a checkout of https://github.com/igorpecovnik/lib.wiki.git  to realize that the current approach makes things harder or even might not work at all (if we want a structured documentation we can use persistent anchors/links with)

[Igor]

The former HTML representation of various docs on armbian.com was pretty much useless 

 

I discussed this problem with plugin author some time ago but he failed to find a solution. Yes, it's terrible.

 

Even when docs will be on the proper level, some people will fail to read them   Further I was thinking about some forum plugin / feature which will pop up some message "Have you read the manual" at posting if user is having less than 3 posts, was registered not long ago and if text "I am new to Linux|Armbian" is found in text

 

EITHER a searchable wiki with unstructured contents that change on a daily basis you can link to (then we can answer any forum question with 'go search the wiki') OR a defined documentation process relying on MD docs that will be postprocessed and creates structured HTML one can link to in a consistent way and a fully blown PDF manual. 

 

@lanefu (has RW Github access) @Tido @miked @Kriston @jeanrhum @vlad59 @Gravelrash - all who claimed or promised help around docs. It's your time to shine   

 

Note: latest documentation sources are lib.wiki but that location and structure just become irrelevant. 

[tkaiser]

Even when docs will be on the proper level, some people will fail to read them   Further I was thinking about some forum plugin / feature which will pop up some message "Have you read the manual" at posting if user is having less than 3 posts, was registered not long ago and if text "I am new to Linux|Armbian" is found in text 

 

There will always be people failing to read/understand documentation (same with discussion contents). But that's not the point.

 

We fail horribly guiding our users to the docs. Please scroll to the top and look at the screenshot. This nearly invisible 'check documentation...' is plain bullshit! Since people don't find it and if they click on it they end up with a wall of text. We fail at thinking about Usability constantly.

 

Instead of such an invisible link in small letters the H3 forum for example (focusing on our most inexperienced user base currently) could have one pinned post on top called "H3 FAQ" that either contains one single sentence and a persistent link to some sort of a H3 FAQ inside the docs or a list of different topics either pointing to individual doc sections or forum topics. If we manage to improve our documentation then it should become normal that all the 'tutorial' posts or forum topics like 'How to backup Armbian?' can be transformed to a specific documentation section outlining different approaches and pointing back to the forums or even contain links to working scripts. But both requires that we can rely on persistent links to documentation sections.

 

Same for other sub forums, same for the download page. What prevents us to outline in big letters that people should read through the specific doc section prior to burning an SD card? Why not putting the link to the relevant portions of documentation where it belongs to? Next or on top of the download buttons.

 

But all of the above requires that we are able to maintain persistent links, which means persistent structure within the documentation. A general purpose wiki approach is quite the opposite since it encourages contributors to change both contents and structure (again and again without even thinking about that the wiki is only editing frontend and not preferred presentation engine!!!).

 

So if you now encourage users to start editing the wiki the whole postprocessing approach (using mkdocs, htmldoc, whatever) will fail. That's what I meant with 'less documents are better'. Since this helps unifying the structure (different 'header depth' means different TOC levels later in PDF -- see the example how different userdoc and the other docs were handled based on current structure) and reminds people that they edit only MD files that are rendered in a different engine later.

 

@Igor: It's that easy, play 10 minutes with mkdocs and htmldoc and you know why the current wiki approach is a step in the wrong direction if we want to postprocess the MD documents and create both good HTML (using anchors to be able to create persistent links!) and a good PDF manual. But if that's not the goal any more and it's just about enabling a bunch of people to fiddle around in a wiki then... it's the wrong engine (no search possible)

[Igor]

So if you now encourage users to start editing the wiki the whole postprocessing approach (using mkdocs, htmldoc, whatever) will fail. 

 

I think we all agree that we need a persistent links to documentations and this can best be achieved with proper tools. I am only pointing out that latest content is in WIKI ... it needs to be glue back together, use filenames which was set or whatever.

 

It's that easy, play 10 minutes with mkdocs and htmldoc and you know why the current wiki approach is a step in the wrong direction

 

Actually if we rely on permalinks within rendered HTML file it should not matter. 

[miked]

I'll experiment with some ideas I have for persistent links.

 

 

To let the public edit documentation, couldn't you let them edit a branch in github (or github wiki), and check that it doesn't break everything whenever you want to pull their changes?

[tkaiser]

 

Just look at the screenshot, look how the URL is constructed. That's what mkdocs does for you after 2 minutes of 'tweaking'. Taking the structure that is present in the ckecked out .md documents and creating nice formatted HTML from it. URLs are called like documents, anchor names depend on internal structure. Everytime a clueless guy starts to edit wiki contents believing only wiki output would count everything breaks. It's that easy.

 

Defining 'internal' structure inside _Sidebar.md worsens everything even more since now you have to parse this file to modify MD documents prior to feeding it to mkdocs. IMO bad.

 

So by giving up on the 'presentation engine' in our github wiki and simply using a home page that states 'Do just edit the pages accessible on the right, don't change page titles, don't change section names, only add stuff and edit structure very carefully' you might get the wiki approach to work IF we want to postprocess the stuff therein (no idea if WE want that still)

 

By adjusting structure levels inside the individual .md docs and minimizing their count the postprocessing efforts are MINIMAL. Just choose the right mkdocs theme, disable search therein and feed the output to htmldoc. And you get a full PDF manual with links, index and so on. And using a different theme you can use HTML output from mkdocs on armbian.com (given that nobody uses the github wiki like a wiki and starts there editing like crazy -- that's the whole point. As soon as people start to use the wiki in the usual wiki way all our persistent links get fucked up automatically)

 

But since only @lanefu looked that much into (and might be able to understand me) I finally stop here since the whole discussion gets boring.

[wildcat_paris]

why don't we add a file in the zip?

 

YOU_HAVE_A_PROBLEM_READMEFIRST_PLEASE.txt

giving basic pieces of advice (check your SDcard, etc.)

and links to the documentation.

 

 

gr@gr ~ $ 7z l Armbian_5.14_Orangepi_Ubuntu_xenial_4.6.2.7z



   Date      Time    Attr         Size   Compressed  Name
------------------- ----- ------------ ------------  ------------------------
2016-06-22 21:05:49 ....A        18558    274521794  armbian.txt
2016-06-22 21:05:55 ....A          819               Armbian_5.14_Orangepi_Ubuntu_xenial_4.6.2.raw.asc
2016-06-22 21:05:50 ....A   1559232512               Armbian_5.14_Orangepi_Ubuntu_xenial_4.6.2.raw
------------------- ----- ------------ ------------  ------------------------
                            1559251889    274521794  3 files, 0 folders

 

 

[tkaiser]

why don't we add a file in the zip?

 

For example the Armbian User manual in PDF format? Sure, we can also re-invent the wheel and start with another set of 'getting started' docs to bundle. But wouldn't it be better to think about how documentation in general could be improved and what's missing in the 'Getting Started' chapter of our current documentation (if there's something missing -- I'm no newbie any more so I'm not able to assess this part of the documentation)?

 

BTW: As an alternative to htmldoc I just stumbled accross mkdocs-pandoc.

[wildcat_paris]

why don't we add a file in the zip?

 

YOU_HAVE_A_PROBLEM_READMEFIRST_PLEASE.txt

giving basic pieces of advice (check your SDcard, etc.)

and links to the documentation.

 

I also thought of BURN_TO_HELL.txt (TK mode)

 

Not a good idea

 

README_FIRST_BOOTING_ISSUES.txt (very short description file as a TO CHECK LIST)

 

BURN_IMAGE_CHECKLIST_README.txt

Edited June 28, 2016 by wildcat_paris
yes I am trolling TK because I like TK

[Tido]

BTW: As an alternative to htmldoc I just stumbled accross mkdocs-pandoc.

 

Is this  different to Igor's approach in this posting?

 

---

I think one document is not enough.

You have to have documents per 'task', i.e. I like Wildcat_P suggestion.

Furthermore, Igor mentioned this also already, I gave some ideas to it. What we are currently suffering is a document to collect the ideas we already agreed on.

Now all this information is spread over these 2 pages of this thread.

I could start to collect this in a Google-Doc and I can give you edit access.

 

I think this would be much more effective - in the office I cannot access Google-Docs so I could start tonight.

[tkaiser]

Is this  different to Igor's approach in this posting?

 

No of course not! Since it makes absolutely no difference whether you deal with 1 md document or a bunch of them! Don't waste time getting too deep into details.

 

Since you still get not the idea what mkdocs could be used for I'm really looking forward to your google docs thingie summarizing what you think you understood. Me personally am leaving this circle now and hope @lanefu doesn't give up.

[miked]

Here's the best I can come up with so far, that looks possible:

 

Required: Permanent links, TOC, searchable 

Desired: Minimal source structure, hard to break.

Not important: Platform independence (documentation source need not work as-is with other software).

 

 

For permanent links, we have fixed file names, and anchor IDs embedded in the source. Something like:

[permalink]: how-to-boot
# How to boot?

Insert SD card...

We process the output of mkdocs so that where "permalink" was in the source, the next anchor is replaced with what we specified.

The link source markdown could be generated by our scripts, then put in the source document. The writer then wouldn't need to create the link text. If it is missing it won't break anything.

 

The rules for editing docs, to avoid breaking links, are:

- Do not change file names

- Do not edit permalink line, or separate it from the section's text

- Do not move a permalink'd section to another file

 

([id] or [anchor] might be preferred over [permalink]. The tag could go after the title if preferred. I think this uses valid markdown syntax.)

 

 

 

 

Edit: These tags are optional, only necessary if we have external links to the documentation section, and if the section title is changed and no longer matches what was linked. If we wanted to avoid cluttering the source with these tags, we could have our scripts generate these lines only for any links that were in the previous mkdocs output but not the new one, indicating a possible change to the section title. These tags would essentially indicate the original section title.

[permalink]: how-to-boot
# Booting your device

After ensuring your power supply...

[wildcat_paris]

All is about the structure and content. Also how to point & fix the common "single point of failure" (= I cannot boot my board with Armbian... please help, if not, I will be whining all along on the forum) anything like BURN_IMAGE_CHECKLIST_README.txt or approaching concept would help to lower basic/common questions on the forum.

Required: Permanent links, TOC, searchable 
Desired: Minimal source structure, hard to break.
Not important: Platform independence (documentation source need not work as-is with other software).

Igor github structure is a simple good start but probably needs refinement.

 

no one wants to follow/get the structure of https://wiki.cacert.org/ (I did the "People's Republic of CAcert" concept 10 years ago, I prefer McCarthy style now)

[Igor]

What about this way?

 

docs.armbian.com

 

mkdocs.yml 

site_name: Armbian Documentations
theme: readthedocs 
markdown_extensions:
    - toc:
        permalink: True
pages:
- 'index.md'
- 'User manual': 'user-manual.md'
- 'Board special':
     - 'H3': 'boards/H3.md'
     - 'Allwinner': 'boards/Allwinner-hardware-conf.md'
- 'build-manual.md'
- 'Changelog.md'

[Tido]

Here I have currently wildly collected most of the information and put in 4 topics suggestion.

 

Everybody who has the link can edit the document, if you are logged in on Gmail you can see who did what.

[wildcat_paris]

 

What about this way?

 

docs.armbian.com

 

 

I would add a dedicated "Support" section with common issues

 

because I can see more people on the forum.

More people (nice for Armbian project) but also a rise on common issues (as TK would say bad SDcard, power supply, etc.)

 

We need to limit common questions (with limited added value) to focus on real question (I have been part of support@cacert.org 2005-2009) as we have limited human resources (we also have to deal with ego management of current team).

 

then BURN_IMAGE_CHECKLIST_README.txt adds common issues & links to "Support" section