[Slackdocs] Page guidelines

David Demelier markand at malikania.fr
Thu Feb 21 12:12:29 CET 2019


It looks like there are many different writing styles on the wiki. I 
think we should uniform that a bit.

1. Page names

Let's keep them simple, examples:

- install_mariadb_on_slackware: BAD, the wiki is about slackware, so 
"on_slackware" is redundant. Also, installing makes the page too 
restrictive. What if the page adds much more documentation than just 
- postgresql: GOOD, generic and future-proof.

I already renamed some pages, I'd to hear if you agree or not. But I 
think it really needs a big cleanup.

2. Page groups

Like the statement above, the following page could have been merged into 
one "firefox"

- firefox_annoyances
- firefox_downloaded_files
- firefox_pdf_viewer

Having too much split pages makes the index and searching too 
complicated. I'll merge them myself.

3. Page templates

It could be very nice if all pages under a specific namespace follow the 
same template. Example in howtos:software

     ====== Introduction ======

     Short summary

     ====== Installation ======

     Short summary

     ====== Usage =======

For this, I propose that all namespaces contain a template file to follow:

- howtos
   - software
     - template
   - security
     - template

And such. Obviously, if you agree I'll do it myself and update pages 

4. Guidelines

As guidelines I propose:

- pages names are always lowercase_with_underscore
- pages names must match a generic term if possible
- pages names must follow the appropriate template file

I think we should add a paragraph about that on the page:


I don't have write access on it, could you please write one?



More information about the Slackdocs mailing list