Tag : techbase

Writing up-to-date tutorials with Doxygen

The other day we were discussing on #plasma about KApiDox and what the Plasma team needed to write awesome documentation. Sebas and Martin were specially complaining about the fact that keeping a tutorial up-to-date was difficult because it is only text which will never be compiled for real by the writer, or not as presented.

The solution

I’d like to share the solution that Doxygen propose (adapted from the Doxygen documentation [1]):

The command is

\snippet <file-name> ( block_id )

Contrary to \include that includes a complete file as source code, this only quotes a fragment of a file. To refer to the same file you are documenting, use this as the <file-name>

For example, the putting the following command in the documentation, references a snippet in file example.cpp residing in a subdirectory which should be pointed to by EXAMPLE_PATH.

 /**
  * ....
  * A resource can easily be added with:
  * \snippet snippets/example.cpp Adding a resource
  * ...

A unique identifier refers to the snippet defined as followed

    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));
//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

The output of the snippet command is:

document->addResource(QTextDocument::ImageResource,
    QUrl("mydata://image.png"), QVariant(image));

What follows

I updated the wiki [2], and now you can continue writing awesome documentation about how to use your libraries.

You know what? The more it goes, the more I think that Techbase is slowly becoming useless… But Schhhhtttttt… this is a secret. 😀

Cheers and have fun !

Sources

[1] http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdsnippet
[2] https://community.kde.org/Guidelines_and_HOWTOs/API_Documentation#Code_Examples_in_APIDOX

We reorganized (most) of the wikis, we need you!

…This post explains in more details what have done on the Community and Techbase, and what belongs where…

So we worked a lot on Community and the structure changed. It’s what I want to write about here.

More details can be found here:

What goes where?

What goes in Community?

You have a KDE project and need a place to coordinate, explain how to build from source or give some code guidelines, please write it under https://community.kde.org/Your_Project and add it (if it’s not already the case) on the front page, where it belongs. This is where the contributors of this project should go to find information about it.

So what goes in Techbase?

In Techbase we thing in term of products. If you have a product that can be build on or extended by third parties (plugins, API, scripting,..) then you should document how to extend it or build on top of it. We are working on a tutorial about this to help you to write this type of documentation. Basically an external developer needs to know how the library work (API), have a high level overview of what can be done (and why), how to troubleshoot or debug when it doesn’t work, how to get help. Of course you can (should?) add a link to you community space to push them to contribute to your project…

You should keep in mind, that this is a reference for people who are not in the KDE community: they are users of your technology. It’s more than possible that your Community space will link to the documentation in Techbase because contributors need this information as well.

What is still to be done?

On our side

Some projects are still hidden in Techbase, and need to be moved to Community. When it’s done we contact you to sort and merge them with your current documentation.

The tutorial section on Techbase is still messy, and we are slowly reorganizing them (see the Guidelines and HOWTOs page). It won’t be all on community! The documentation on, say, how to localize a program with Ki18n definitely belongs to Techbase, whereas how to use git on our infrastructure doesn’t.

We are working with the VDG team to organize cleverly Techbase frontpage

Still some links are red, we are trying to correct that as fast as we can.

On your side:

It really depends on your project and products but overall:

  • Check that your links to the wikis are still up to date in your websites.
  • Maybe take this opportunity to be sure all your documentation is up-to-date? Delete old or irrelevant pages?
  • If you are concerned, add your product to the Techbase front page and begin documenting
  • Tell us if something is missing, should be enhanced or anything else (but with argumentation please… no “Better before, it was” will be accepted 🙂

We really need you for this!

This said, as usual:

Cheers and have fun!


PS: Consider supporting KDE e.V.! It might be small for you but it’s great for the community.
Via Paypal for one-time donations
Become an ongoing supporter and official supporting member

post image

Sprint at CERN: things got done!

Whhoooo! Almost one week before I only gave a thought to write this post.
Reading myself again, I think I have to much to say… Let’s split so that you don’t get (too much) bored 🙂

The sprint

This sprint was my first meeting with KDE contributors. I broke the first rule my parents told me about internet: “Do never meet the people you are chatting with on the web!”. Anyway it was a really, really good experience.

We had good food (thank you W2L!), we had a lot of noise (thank you W2L!), and we had a productive team (thank you @alexmerry, @fringing and @rharisch!).

As I already wrote in previous posts, my team was working on reorganizing and updating Techbase [1].
When we planned this we decided do focus on this wiki only. But nothing worked as planned…we just did a lot more!

First steps

KDE operates three wikis:

If the content of the first one was really easy to define, it wasn’t so clear what should go to community and techbase. Our first goal was to define a clear and precise line to discriminate the content of the two other wikis.

Defining this line took us not less than 2 (two!) days. We thought in term of Who is the target of this wiki? and had a lot of discussions about specific and borderline cases. We talked on IRC to get second views and see if our ideas where reasonable. We ended with these presentation texts (see [2]):

Techbase.kde.org is primarily aimed at external developers.
It provides documentation and help for developers building on or extending KDE products in their own projects.

Community.kde.org is the working area for the KDE community.
It provides a place for sharing information within the community, including policies, guidelines and coordination.

I’ll come back to this in a dedicated post in a few time… You already can read some details on this on Alex’s blog [3].

Hard work with moving pages…

When our ideas were clearer, we began to follow our new rules and reorganize the wikis for real. We realized that most of the pages in Techbase were belonging to Community, and that we had thus to work hard on Community as well.

This wouldn’t have been possible without @neverendingo and @nicolas17 who gave us temporary more rights on Community and Techbase, helped us to massively move pages and replace them by links to the new position and so on…

We are not completely done, but please let us know if you don’t find something… We might have forgotten some links.. You can already go on the wiki to see how it is slowly changing (for the best!).

I’ll be back with more info later!

Cheers and have fun!

What we did this week wouldn’t have been possible without the support of KDE e.V. Consider supporting it!
Via Paypal for one-time donations
Become an ongoing supporter and official supporting member

Links

[1] https://techbase.kde.org
[2] https://wiki.kde.org
[3] https://randomguy3.wordpress.com/2016/03/08/wiki-reorganisation/

post image

Sprint at CERN, hey you wanna help?

This is rather a short post…

The sprint at CERN for WikiToLearn, the VDG and Plasma team and to reorganize Techbase is beginning on Monday. As I already said in previous posts about reorganizing Techbase: having clean and organized wiki is really beneficial for the community. It will be easier to find the information, and thus the community will be more efficient.

People asked on the mailing list if they could remotely help… I just want to say: Of course! To work on the Techbase, you can join us on #kde-www and #kde-devel (on freenode) and see what’s still to do, and what the plan is.

I cannot already say how we are going to be organized but anyway, just ask on the channels (you can ping me @ochurlaud as well).

As I said, a short post: I’m already done.

Next week, ping us on #kde-www, and hack with us!

Cheers, and have fun!!
Olivier

post image

Sprint at CERN: it’s coming….

The sprint at CERN is already almost there.

I was quite afraid that our part (reorganizing the Techbase wiki) would not be doable because of the problem KDE had on all the wikis. Because of a severe spam attack [1], all edition rights were suspended until a better authentication was implemented.

It is now done! (kudos @neverendingo, @bcooksley, @Nikerabbit and all people who contributed to that)

What are we going to do there?

As already written in my previous post, this sprint is a WikiToLearn [2] sprint. Other projects, such as Plasma and the VDG Team were kindly invited to join. I’ll be part of the team working on tidying up the Techbase wiki [3].

This includes moving the KDE4-related documentation to an archive namespace, (re?)moving old drafts and duplicate documentation, checking that everything we leave in the main namespace is up-to-date. And certainly more.

What already began… What can you already do?

I’ve seen that @jucato already began to port some tutorials from KDE to KF5. He added some tasks that I regrouped here [4]. It’s not comprehensive but still a good start.

Begin to have ideas, create tasks in the project techbase on our Phabricator, and do whatever usefull I haven’t thought of!

Keep in mind…

KDE ev. is supporting this sprint: I know it is worth it and that this money is well spent… Let’s rock this!

Cheers and have fun!

Links

[1] http://marc.info/?l=kde-devel&m=137466627807667&w=2
[2] http://wikitolearn.org/
[3] https://techbase.kde.org
[4] https://phabricator.kde.org/T1399