[pkg-apparmor] Navigation through our wiki pages

[intrigeri]

Hi,

as promised during our last OPW meeting, I did a first pass for each
user story, pretended I was that user, and taken note of what seemed
to be the most obvious current navigation path through our
documentation to address my needs. Additionally, in most cases I've
added a personal evaluation of the current state of things, and
sometimes ideas for improving it.

I'm writing this offline, so cannot put my results on the wiki,
hence this dump:

- Ship an existing AppArmor profile in the same Debian package as the
  confined software:
  - current path: AppArmor -> AppArmor/PackageMaintainers
  => works for migrating a profile from aa-p-extra, once the doc is there
  => works for importing an existing upstream profile

- Testing AppArmor confinement before uploading a new version of
  a package
  - current path: AppArmor -> AppArmor/PackageMaintainers ->
    AppArmor/PackageMaintainers#Testing
  => OK

- New AppArmor profile
  - current path for package maintainers: AppArmor ->
    AppArmor/PackageMaintainers -> dead end: doesn't mention why nor
    how to have the profile reviewed and possibly merged upstream
  - current path for other contributors: AppArmor ->
    AppArmor/Contribute -> "Create or patch profiles: Contribute to
    Upstream" -> AppArmor/Contribute/Upstream
  - lacks doc for new-profile usertag

- Update an AppArmor profile to include upstream improvements
  - current best path: AppArmor -> AppArmor/Contribute ->
    "Create or patch profiles: Contribute to Upstream" ->
    AppArmor/Contribute/Upstream, which (probably rightfully?) doesn't point to
    AA/Contribute/Import
  - lacks a link to AppArmor/Contribute/Import from AA/Contribute,
    with a link text that clearly is about this user story
  - lacks doc for merge-from-upstream usertag: add it to AA/Contribute/Import?

- Modify an already shipped AppArmor profile
  - current path: AA -> AA/Contribute -> "Create or patch profiles: Contribute
    to Upstream."; good enough?
  - lacks doc for the modify-profile usertag

- Upstream Debian changes made on an AppArmor profile we ship
  - current path for Debian package maintainers: AA ->
    AppArmor/PackageMaintainers: dead end. AA/PM should link to
    AA/Contribute/Upstream in a different or additional way, as
    "Please read our explanation of the relationship between Upstream
    and Debian first." doesn't seem to address this user
    story's needs.
  - current path for other contributors: AA -> AA/Contribute -> "Create or
    patch profiles: Contribute to Upstream.", which does not very clear that
    it's also about upstreaming Debian changes
  - lacks doc for the merge-to-upstream usertag; add to AA/C/Upstream?

- Find out if a problem with a confined software is AppArmor related (users)
  - current path: AA -> AA/HowToUse -> AppArmor/HowToUse#Debug ->
    AA/Debug
  - lacks doc for help-needed usertag
  - lacks doc for buggy-profile usertag

- Find out if a bug is AppArmor related (maintainers)
  - current path: AA -> AppArmor/PackageMaintainers -> AA/Debug
  - lacks doc for help-needed usertag
  - lacks doc for buggy-profile usertag

- Other AppArmor related problems
  - current path: mostly likely, AA -> AppArmor/PackageMaintainers
    that has a link to AA/Contribute at the very bottom


=> IMO we should:

 0. Remove the Goals section for AA/Contribute, until we know what our
    goals for Stretch are.
 1. remove the AppArmor/PackageMaintainers page, split its content
    into goal-oriented sub-pages of AA/Contribute
 2. Remove the direct link to AppArmor/PackageMaintainers from the
    w.d.o/AppArmor homepage
 3. Improve AppArmor/Contribute so that it points to the
    aforementioned goal-oriented sub-pages of AA/Contribute
 4. Reorganize "How to help" to be:
    - more general, as in addresses maintainers' needs, not only the
      needs of newcomers on our team (in general I think the best
      long-term strategy is to blur as much as possible the boundary
      between "AA-team-member" and "Debian package maintainer" ;)
    - more goal-oriented, based on our user stories

e.g. (just to give you an idea):

How to participate
==================

* Ship an AppArmor profile in "your" package
  - AA/Contribute/ImportProfileFromUpstream
  - AA/Contribute/ImportProfileFromExtra
  - test profiles: AA/Debug

* Upstream Debian changes to AppArmor profiles
  - Contribute/Upstream

* Improve quality of AppArmor profiles
  - ...

* Misc.
  - Update profiles shipped in aa-p-e to the latest upstream
    version --> AA/Contribute/MergeProfileFromUpstream (which would be
    current AA/Contribute/Import)
  - Fix bugs in the packages we maintain

* etc.

Cheers,
-- 
intrigeri