[Printing-architecture] OpenPrinting - Documentation urgently needed!

[Printing-architecture] OpenPrinting - Documentation urgently needed!

[Till Kamppeter]

Hi,

now, with good parts of the New Architecture of printing and scanning 
done, we see a lot of new code but we are really lacking documentation 
for our software.

We already had some discussion about documentation, different types, 
ways of obtaining, ... on the OpenPrinting micro-conference on the Linux 
Plumbers 2022:

Slides:
https://lpc.events/event/16/contributions/1160/attachments/943/1853/lpc-printing-docs-2022.pdf
https://lpc.events/event/16/contributions/1160/attachments/943/1860/documentation-openprinting-extra.pdf

Recording:
https://www.youtube.com/watch?v=XoNydHus4VU

Now I would like to find some people who could help us in writing 
documentation, making drawings and graphics, ... Therefore I am posting 
this mail on the OpenPrinting mailing list but also direct it to people 
who already have done documentation for OpenPrinting, spoke up that they 
would like to volunteer on documentation, have contributed drawings and 
graphics (or have done nice one in their projects) ...

What we need is documentation for:

- Developers: Library functions of libcupsfilters, libppd,
   libpappl-retrofit, cpdb-libs, ... Documentation for individual
   functions and data strutures is put right into the source code, tools
   like Michael Sweet's codedoc generate the actual documentation from
   that. Requires knowledge about coding.

- Admins: How to configure and set up things in networks

- Users: Easy steps to get printing just work.

Documentation will be posted on our web site but also included in source 
packages.

We need reference manuals, man pages, HOWTOs, tutorials, also teaching 
things in YouTube videos is welcome ...

So everyone who likes to contribute something is welcome to do so! 
Please speak up here and tell what you like to contribute.

I will also run an OpenPrinting Roadmap Sprint on Sep 8, in the IIT 
Mandi in Northern India, on the Opportunity Open Source which I am 
organizing there.

https://events.canonical.com/event/35/

Depending on your answers and suggestions here I will do a session about 
documentation. You could connect by video to it and participate, or if 
you are near Mandi, come in person.

Let us not only have great printing and scanning but also great 
documentation for it!

    Till

Re: [Printing-architecture] OpenPrinting - Documentation urgently needed!

[Amin Bandali]

Hi Till, (all,)

I'm interested in helping out with the docs, particularly developer
docs.  I recently asked my manager if I could spend some of my time
helping with this, and essentially he said yes, depending on the
workload and the priority of my other tasks at hand at a given time.
Later on I hope to spend time on this outside work as well, as soon as
my schedule opens up a bit more.

I'll start by taking some time to skim through the library functions
for the libraries Till mentioned, and try to get a lay of the land.
If folks have any suggestions or tips about which library and/or what
modules specifically may be good places to start, I'd appreciate the
advice.

Best,
-a

Re: [Printing-architecture] OpenPrinting - Documentation urgently needed!

[Till Kamppeter]

On 31/08/2023 18:12, Amin Bandali wrote:
> Hi Till, (all,)
> 
> I'm interested in helping out with the docs, particularly developer
> docs.  I recently asked my manager if I could spend some of my time
> helping with this, and essentially he said yes, depending on the
> workload and the priority of my other tasks at hand at a given time.
> Later on I hope to spend time on this outside work as well, as soon as
> my schedule opens up a bit more.
> 
> I'll start by taking some time to skim through the library functions
> for the libraries Till mentioned, and try to get a lay of the land.
> If folks have any suggestions or tips about which library and/or what
> modules specifically may be good places to start, I'd appreciate the
> advice.

Amin, we have 4 principal libraries which need developer documentation 
and you are highly welcome to work on that:

- libcupsfilters
- libppd
- cpdb-libs
- pappl-retrofit

Note that on Michael Sweet's projects (cups, libcups, pappl) Mike is 
already taking care of the documentation by himself.

To simplify our work at OpenPrinting we want to do all the documentation 
with the same tools, and as Michael has started with his codedoc tool on 
his own projects we want to adopt it for the rest of our libraries where 
I am leading the development.

See the sessions/slides of last year's OpenPrinting micro-conference 
which I have cited in my initial e-mail.

So your work would be:

1. Check the header and parameter comments of all API functions whethet 
they are actually there and also are in correct sysntax
2. Run the codedoc utility over the source code base and check whether 
everything appears correctly in the browser.
3. Add/complete the documentation which needs to be done manaually 
(Introduction, ...)

The priorities are:

1. cpdb-libs
    Needed for desktop integration. All print dialogs should use CPDB

2. libcupsfilters
    Needed for creation of printer and scanner drivers.

3. pappl-retrofit
    Needed for turning legacy CUPS printer drivers and SANE scanner
    drivers into Printer/Scanner Applications

4. libppd
    Usually used by pappl-retrofit and legacy CUPS filters (cups-filters)
    and not directly by developers, but for sake of completeness we
    should document it, too.

I hope this is sufficient info to get started. Do not hesitate to ask me 
if you have questions.

    Till

Re: [Printing-architecture] OpenPrinting - Documentation urgently needed!

[Amin Bandali]

Hi Till,

Sorry for my slow reply, and many thanks for your explanations.
That is very helpful and certainly sufficient, and I'll indeed
be sure to ask if I have any questions.

Thanks again,
-a