TechBase

While cleaning up the TechBase Getting Started pages for the Git move, I've been noticing a lot of other pages that are either incorrectly located in the TechBase hierarchy, are lacking in quality or detail, or just don't belong there at all.

So, before you add anything to TechBase, ask yourself two key questions:

  1. Does this really belong in TechBase?
  2. Where in TechBase does it really belong?

So how do you decide if stuff belongs on TechBase? In KDE we have three main wiki's serving three different purposes:

  • TechBase - Technical reference documentation, primarily directed at external technical users
  • Community - Internal community documentation and co-ordination
  • UserBase - End user documentation

Where the difference lies between TechBase and Community for Project documentation can be tricky, but I think of it as roughly along the lines of Stable versus Unstable.

TechBase is the formal stable documentation, how we do things, how external parties can use what we produce, stuff that a project's external technical users need to know. It is facing outwards.

Community is the informal unstable documentation for internal consumption only, what a team is planning to do, how they are going to do it, meeting minutes, stuff that a project's internal development team needs to know. It is facing inwards.

So documenting how someone outside your team can write a plugin for your application goes to TechBase, documenting how your team designs and builds that plugin infrastructure goes to Community. TechBase will usually only change after a release, Community will constantly be changing.

So where to put stuff in TechBase? If it affects KDE as a whole, add it at an appropriate place under one of the existing top-level sections. If it just affects a single module or project within KDE, then add it under the Projects top-level section, organized by Application or Module as appropriate.

Please don't start new top-level pages.

Here's the current top-level sections to choose from:

  • Getting Started
  • Development
  • Schedules
  • Policies
  • Contribute
  • ISV
  • KDE System Administration
  • Projects
  • Research
  • Localization
  • Paths

(Yes, some of those top-levels could be moved lower down the hierarchy).

We still have a lot of community related content under TechBase Projects, it would be great if projects could put aside a couple of hours to clean up their TechBase entries and move community related material over to their pages on Community. It might also be useful to add reviewing of your TechBase and UserBase pages as part of your pre-release check-list so your technical and end users are able to find up-to-date information.

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Maintenance

For years I was kind of the maintainer of TechBase. I checked all changes every day. And fixed each change that was out of place. I've stopped doing this, it takes *a lot of time*. I hope someone else will pick it up and keep TechBase clean. It's a challenging task, though.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.