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

_______________________________________________
Freeipa-devel mailing list
Freeipa-devel@redhat.com
https://www.redhat.com/mailman/listinfo/freeipa-devel

Reply via email to