236 lines
6.3 KiB
Markdown
236 lines
6.3 KiB
Markdown
# Knowledge Article System - User Guide
|
|
|
|
## Overview
|
|
|
|
The Knowledge Article System is a simple desktop application for documenting and searching IT processes, troubleshooting steps, and other technical knowledge.
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Starting the Application
|
|
|
|
1. **Start the backend server:**
|
|
- Navigate to the server folder
|
|
- Run the server executable or `node server.js`
|
|
- Server will run on port 9000
|
|
|
|
2. **Start the frontend:**
|
|
- Navigate to the frontend folder
|
|
- Run `npm run dev`
|
|
- Open your browser to `http://localhost:5173`
|
|
|
|
---
|
|
|
|
## Using the System
|
|
|
|
### Searching for Articles
|
|
|
|
1. When you first open the application, you'll see a list of all knowledge articles
|
|
2. Use the **search bar** at the top to find specific articles
|
|
3. You can search by:
|
|
- **KA Number** (e.g., "KA001")
|
|
- **Article Title** (e.g., "password reset")
|
|
- **Article Content** (e.g., "printer")
|
|
|
|
4. Search results update automatically
|
|
5. Clear the search box to see all articles again
|
|
|
|
### Viewing an Article
|
|
|
|
1. Click on any article in the list to view it
|
|
2. The article will display:
|
|
- KA Number (e.g., KA001)
|
|
- Title
|
|
- Creation date
|
|
- Full content
|
|
3. Click the **← Back** button to return to the article list
|
|
|
|
### Creating a New Article
|
|
|
|
1. From the article list view, click the **+ Create New Article** button
|
|
2. Enter the article information:
|
|
- **Title:** Brief description of the issue or process
|
|
- **Content:** Detailed steps, troubleshooting tips, or explanations
|
|
3. Click **Save** to create the article
|
|
- The system will automatically assign a KA number (KA001, KA002, etc.)
|
|
4. Click **Cancel** to discard and return to the list
|
|
|
|
### Editing an Article
|
|
|
|
1. Open the article you want to edit
|
|
2. Click the **Edit** button
|
|
3. Make your changes to the title or content
|
|
4. Click **Save** to save your changes
|
|
5. Click **Cancel** to discard changes and return to viewing the article
|
|
|
|
### Deleting an Article
|
|
|
|
1. Open the article you want to delete
|
|
2. Click the **Delete** button
|
|
3. Confirm that you want to delete the article
|
|
4. The article will be permanently removed
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### Writing Good Knowledge Articles
|
|
|
|
**Use Clear Titles**
|
|
- ✅ "How to Reset User Password in Active Directory"
|
|
- ❌ "Password Thing"
|
|
|
|
**Structure Your Content**
|
|
- Start with a brief description of the issue or process
|
|
- List steps clearly and in order
|
|
- Include any important warnings or notes
|
|
- Add troubleshooting tips if applicable
|
|
|
|
**Example Format:**
|
|
```
|
|
Issue: User cannot access shared network drive
|
|
|
|
Solution:
|
|
1. Verify user has correct permissions
|
|
2. Check network connectivity
|
|
3. Restart Windows File Explorer
|
|
4. If issue persists, check group policy settings
|
|
|
|
Notes:
|
|
- This issue commonly occurs after Windows updates
|
|
- Always verify the drive is mapped correctly first
|
|
```
|
|
|
|
**Keep It Updated**
|
|
- When you discover new information or better solutions, edit the article
|
|
- Delete outdated articles that are no longer relevant
|
|
|
|
**Use Consistent Naming**
|
|
- Keep KA titles consistent (e.g., all start with "How to..." or describe the issue)
|
|
- This makes searching easier
|
|
|
|
### Search Tips
|
|
|
|
**Use Keywords**
|
|
- Search for the most unique or specific term
|
|
- Example: Search "VPN" instead of "connection issue"
|
|
|
|
**Search by KA Number**
|
|
- If you know the KA number, search for it directly (e.g., "KA015")
|
|
- This is the fastest way to find a specific article
|
|
|
|
**Try Different Terms**
|
|
- If you don't find what you need, try synonyms
|
|
- Example: "login" vs "sign in" vs "authentication"
|
|
|
|
---
|
|
|
|
## Common Workflows
|
|
|
|
### Documenting a New Process
|
|
|
|
1. Click **+ Create New Article**
|
|
2. Title: "How to [process name]"
|
|
3. Write step-by-step instructions in the content area
|
|
4. Save the article
|
|
5. Share the KA number with your team
|
|
|
|
### Solving a Recurring Issue
|
|
|
|
1. Search for existing articles about the issue first
|
|
2. If found: Review the solution and update if needed
|
|
3. If not found: Create a new article documenting the solution
|
|
4. Next time someone has the issue, just search and share the KA number
|
|
|
|
### Quick Reference During Support Calls
|
|
|
|
1. While on a support call, search for the relevant issue
|
|
2. Open the article and follow the documented steps
|
|
3. Update the article after the call if you discovered anything new
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "No articles found"
|
|
- Check your search term - try a broader search
|
|
- Clear the search box to see all articles
|
|
- If truly no articles exist, create the first one!
|
|
|
|
### Can't save an article
|
|
- Make sure you've entered a title (content is optional)
|
|
- Check that the backend server is running
|
|
- Refresh the page and try again
|
|
|
|
### Article list not updating after creating/editing
|
|
- Refresh the browser page
|
|
- Check that both frontend and backend are running
|
|
|
|
### Server won't start
|
|
- Make sure port 9000 is not in use by another application
|
|
- Check that all dependencies are installed (`npm install` in the server folder)
|
|
|
|
---
|
|
|
|
## Technical Details
|
|
|
|
### Data Storage
|
|
- All articles are stored in a local SQLite database (`ka.db`)
|
|
- Located in the server folder
|
|
- **Important:** Back up this file regularly to prevent data loss
|
|
|
|
### System Requirements
|
|
- Node.js installed
|
|
- Modern web browser (Chrome, Firefox, Edge)
|
|
- Ports 9000 (backend) and 5173 (frontend) available
|
|
|
|
### Backing Up Your Knowledge Base
|
|
|
|
**Manual Backup:**
|
|
1. Stop the backend server
|
|
2. Copy the `ka.db` file to a backup location
|
|
3. Restart the server
|
|
|
|
**Recommended Schedule:**
|
|
- Weekly backups at minimum
|
|
- Daily backups if creating/editing articles frequently
|
|
|
|
### Restoring from Backup
|
|
|
|
1. Stop the backend server
|
|
2. Replace `ka.db` with your backup copy
|
|
3. Restart the server
|
|
4. Refresh the frontend
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| Action | How To |
|
|
|--------|--------|
|
|
| Search | Type in the search bar at the top |
|
|
| View article | Click on an article in the list |
|
|
| Create new | Click "+ Create New Article" button |
|
|
| Edit | Open article → Click "Edit" |
|
|
| Delete | Open article → Click "Delete" → Confirm |
|
|
| Go back | Click "← Back" button |
|
|
|
|
---
|
|
|
|
## Need Help?
|
|
|
|
Since this is an internal tool for our IT team:
|
|
- Ask a team member who has used it before
|
|
- Check this guide for common tasks
|
|
- If you find a bug or have a feature request, let Matt know
|
|
|
|
---
|
|
|
|
## Version History
|
|
|
|
- **v0.0.1 (MVP)** - Basic CRUD operations, search functionality
|
|
- Create, view, edit, delete articles
|
|
- Search by title, content, or KA number
|
|
- Auto-generated KA numbers
|