From: bugzilla@dpdk.org
To: dev@dpdk.org
Subject: [Bug 1356] Documentation structure, additions and cleanup
Date: Wed, 10 Jan 2024 10:42:06 +0000 [thread overview]
Message-ID: <bug-1356-3@http.bugs.dpdk.org/> (raw)
[-- Attachment #1: Type: text/plain, Size: 2399 bytes --]
https://bugs.dpdk.org/show_bug.cgi?id=1356
Bug ID: 1356
Summary: Documentation structure, additions and cleanup
Product: DPDK
Version: unspecified
Hardware: All
OS: All
Status: UNCONFIRMED
Severity: normal
Priority: Normal
Component: dts
Assignee: dev@dpdk.org
Reporter: juraj.linkes@pantheon.tech
CC: juraj.linkes@pantheon.tech, probb@iol.unh.edu
Target Milestone: ---
There are different aspects we could and should document:
* User documentation
* Developer documentation
* Api documentation
* Test suite documentation
Additionally, this page outlines what good documentation should contain:
https://documentation.divio.com/.
User Documentation
The user docs are what we have in doc/guides/tools. These should contain the
tutorials and how-to guides about testbed setup and how to run/configure DTS.
There may be parts which would be better placed in developer documentation
(such as the docs guidance).
Developer Documentation
The developer docs should be understanding-oriented. These should contain the
architecture, what are good (and bad) coding practices with explanations, what
to put into a commit message and so on.
There could also be some tutorials and how-to guides.
There should probably two parts, one for framework developers and one for test
suite developers. The test suite developers docs may actually be in the user
docs.
We don't a clear where we'd put the developer docs.
API Documentation
This is the reference mainly for framework developers, but test case developers
would find it useful as well. The place to put these has been discussed and
would be placed alongside DPDK API docs.
Test Suite Documentation
This is different from the test suite developer docs mentioned above. The test
suite developer docs is about how to implement a test suite and related
resources. This documentation is about documenting the test suite itself - what
it's testing, what configuration is needed and so one.
The place to put this documentation is currently the test suite Python file. If
we adopt a YAML-based test case definition file, we may need to move some (or
all) of it to the YAML file.
--
You are receiving this mail because:
You are the assignee for the bug.
[-- Attachment #2: Type: text/html, Size: 4393 bytes --]
reply other threads:[~2024-01-10 10:42 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=bug-1356-3@http.bugs.dpdk.org/ \
--to=bugzilla@dpdk.org \
--cc=dev@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).