Hi Jean,
I think this is a good approach at this time. Further thought: If we
don't yet have a wiki page where someone (not necessarily you) lists
these issues as they come in (so we can track them), then we should
set one up. People can then see what's needed and put their name down
to work on it. Forwarding initial contact to list is important, but a
tracking page on wiki is also needed.
Yes, it would be a good idea to keep track of these bugs, otherwise
they just subside into the depths of the ML's message history. I'll
write up what I've got already bookmarked in my mail.
My main questions are to do with how and where we write/edit help:
* In the Help files themselves? (If so, where?)
There has been a project for a wiki-based help in the pipeline for a
few months but, for the moment, the work still involves checking out
the codebase from Git and editing files within it.
* By attaching a file (what format?) to the issue, so someone else can
incorporate it in the help?
Hmmmmm, well, to obtain the content to edit, someone would have to
procure it from Git. It would probably be simpler if a person wanting
to work on the help files were to work on their own local copy.
And what to do if someone on the Docs team finds Help that needs
copyediting, enhancement, etc? Open an issue about it, attaching an
edited/revised version? Edit the Help file directly?
I think the idea would be that someone working on one of the bug
reports would come and discuss the resolution of the problem here on
the ML with the rest of the team, or at least come and ask questions
here when in doubt.
Depending on the length and detail of the answer, this might become
part of an existing chapter of the Contributors Guide, or it could be
a chapter on its own. IMO it's very important to distinguish between
how to work on the Help vs how to work on the user guides.
i think you're right that there should be a dedicated chapter on the
subject, and that it's important to teach newcomers the distinction
between documentation and the software's built-in help.
I'll take this on as a task to do along with revising the Alfresco
content of the contributor docs.
Perhaps both subjects would merit writing-up on the wiki, too, but we
should perhaps be careful about duplicating coverage because of the
probable future emergence of conflicts in the info. With that it mind,
which is the best way to go? Wiki only? Wiki plus contributor docs?
Contributor docs only?