[Freedombox-discuss] Discussion: Problems with FreedomBox documentation

[znoteer at mailbox.org]

Hello list,

> Le 30 octobre 2018 à 03:32, Joseph Nuthalapati <njoseph at thoughtworks.com> a écrit :
> 
> 
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA512

This is something I might be able to help with, though I suggest so cautiously.

> 
> Our documentation on the Debian wiki[1] currently has the
> following problems:
> 
> 1. Cannot keep pace with the development

I have no idea what time commitment is required, nor, at the moment, how much free time I will have in the near future.  Thusly, I don't know if I could help mitigate this problem.

> 2. Not written for a non-technical audience in mind

I could probably help fix this problem.  I've taken comp sci classes, and farted around with computers for a long time, but I am not uber-techno geek.  The other side of this coin is that I would need lots of help understanding the ins and outs of fbx.  Are the true geeks ready and willing to share their knowledge?  I've done a tiny bit of technical writing.  In my experience, getting answers to emails from geeks is the biggest problem.

> 3. Has a high barrier to entry (account creation, wiki syntax,
> unfamiliar UI)

I'm not sure I understand this problem, at least not from the end user's point of view: an account isn't necessary to read the docs.  As for myself, I don't know what wiki you use.  I've used a couple of different wikis and markup systems.  Syntax can be learned.

> 4. No separate documentation for the stable and
> testing/unstable versions of FreedomBox

Is it feasible to maintain documentation for testing/unstable?  It's a moving, constantly evolving target.  Things change to quickly to be documented for the end user.  It also requires the most developer access to figure things out (see point 2 above).  I'd probably feel more at ease helping with the stable docs.


Any comments about my comments?

--
znoteer
znoteer at mailbox.org