[Freeipa-devel] FreeIPA documentation: getting started & devel docs (FOSDEM takeaways - Software Archaeology for Beginners)

[Petr Spacek]

Hello list,

I have seen talk "Software Archaeology for Beginners" from FOSDEM 2014 [1] and 
I have couple notes:

1) User docs:
Make sure that project's documentation tells its own story:
Documentation is not so useful if it is a bunch of unrelated documents. Make 
sure that there is 'introduction' document starting with project description. 
The 'story' should continue to installation and very basic configuration and 
use cases.

There should not be a 'gap' between steps like missing steps between 
installation and client configuration etc.

We have something like that in RHEL IdM guide. Should we add "Getting Started" 
link to the very beginning of
http://www.freeipa.org/page/Documentation#User_Documentation ?

Maybe the RHEL guide is too huge and scary for 'getting started' so we would 
need to write something/compile it from existing blogs posts etc.


2) Pictures with a story are nice:
Diagrams with system components are more useful when they *visualize some 
basic workflows step by step*.

Imagine one SSSD client and one IPA server and describe what happens if the 
user enters his username and password to login prompt.

- Arrow #0 from NSS db /passwd/ to SSSD component /s1/ with description /d/
- Arrow #1 from SSSD component /s1/ to IPA component /i1/ with description /d/
- Arrow #2 from NSS db /shadow/ to SSSD component /s2/ with description /d/
- Arrow #3 from SSSD component /s2/ to IPA component /i2/ with description /d/
etc.

Such diagram not only helps to new developers but also gives tremendous help 
to people debugging the whole solution. (We have to admit that debugging is 
always PITA.)


As usual, this sounds like a good task for newcomers (sorry Adam! :-).

[1] 
http://video.fosdem.org/2014/Janson/Saturday/Software_Archaeology_for_Beginners.webm

-- 
Petr^2 Spacek