I have seen talk "Software Archaeology for Beginners" from FOSDEM 2014  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
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
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/
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
As usual, this sounds like a good task for newcomers (sorry Adam! :-).
Freeipa-devel mailing list